No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Computer, Inc. Printed in the United States of America.
No licenses, express or implied, are granted with respect to any of the technology described in this book. Apple retains all intellectual property rights associated with the technology described in this book. This book is intended to assist application developers to develop applications only for Apple Macintosh computers.
Apple Computer, Inc.
20525 Mariani Avenue
Cupertino, CA 95014
408-996-1010
Apple, the Apple logo, APDA, AppleLink, AppleTalk, ImageWriter, LaserWriter, Macintosh, and StyleWriter are trademarks of Apple Computer, Inc., registered in the United States and other countries.
ColorSync, Finder, PowerBook, QuickDraw, QuickTime, ResEdit, and System 7 are trademarks of Apple Computer, Inc.
Adobe Illustrator and PostScript are trademarks of Adobe Systems Incorporated, which may be registered in certain jurisdictions.
AGFA is a trademark of Agfa-Gevaert.
America Online is a service mark of Quantum Computer Services, Inc.
Classic is a registered trademark licensed to Apple Computer, Inc.
CompuServe is a registered service mark of CompuServe, Inc.
FrameMaker is a registered trademark of Frame Technology Corporation.
Helvetica and Palatino are registered trademarks of Linotype Company.
Internet is a trademark of Digital Equipment Corporation.
ITC Zapf Dingbats is a registered trademark of International Typeface Corporation.
MacPaint is a registered trademark of Claris Corporation.
NuBus is a trademark of Texas Instruments.
Motorola is a registered trademark of Motorola Corporation.
Simultaneously published in the United States and Canada.
LIMITED WARRANTY ON MEDIA AND REPLACEMENT
ALL IMPLIED WARRANTIES ON THIS MANUAL, INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE LIMITED IN DURATION TO NINETY (90) DAYS FROM THE DATE OF THE ORIGINAL RETAIL PURCHASE OF THIS PRODUCT.
Even though Apple has reviewed this manual, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS MANUAL IS SOLD “AS IS,” AND YOU, THE PURCHASER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY.
IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS MANUAL, even if advised of the possibility of such damages.
THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty.
Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.
Listing 1-0
Table 1-0
Contents
Display Manager
Contents
About the Display Manager1-6
Window Repositioning by the Display Manager1-7
When the User Removes a Display1-8
Display Manager Problems Moving Windows1-9
When the User Moves the Menu Bar1-11
Display Modes1-13
Video Mirroring1-16
Using the Display Manager1-17
Handling Events in Response to Display Manager Changes1-19
Handling the Display Notice Event as a High-Level Event1-22
Handling the Display Notice Event Outside of an Event Loop1-25
Managing Windows In Response to the Display Notice Event1-25
Determining the Characteristics of the Video Devices1-27
Setting Configurations and Display Modes for Video Devices1-28
Display Manager Reference1-29
Constants1-30
Display Notice Event Keywords1-30
Active Device Only Values1-32
Switch Flags1-33
Functions1-33
Getting Video Devices1-33
Determining Display Modes and Display Configurations1-38
Changing Display Modes and Display Configurations1-44
Adding and Removing Video Devices From the Device List1-56
Registering and Removing A Display Notice Event-Handling Procedure1-61
Drawing the Desktop1-63
Application-Defined Function1-64
Summary of the Display Manager1-65
Display Manager
This chapter explains how the Display Manager allows users to dynamically change the arrangement and display modes of the monitors attached to their computers. For example, users can move their displays, add or remove displays, switch displays to higher or lower screen resolutions, and move the menu bar from one display to another—all without restarting their computers. When the user changes the display environment (as when disconnecting a display, for example), the Display Manager further assists the user by repositioning standard windows so that the user can find them in the new display environment.
Read this chapter to determine whether your application must move its own windows instead of relying on the Display Manager to move them. For example, if your application implements a tool palette that lacks a title bar, and the user disconnects the monitor that displays the tool palette, your application must move your tool palette to the main screen where the user can find it. Because the Display Manager never resizes windows, you should read this chapter to determine whether to resize your application’s windows after a display configuration change.
You should also read this chapter to learn how your application should respond to display environment changes if your application relies on display information that it stores internally. For example, if your application caches display positions, GDevice records for displays other than the main screen, or the value in the screenBits.bounds field of the screenBits global variable, this information may become invalid after the user changes the display configuration without restarting the computer.
The Display Manager is available on all Power Macintosh computers and on color-capable Macintosh computers running system software version 7.5.
Applications that use only the standard window definition functions provided by the Window Manager generally do not need to use the Display Manager. See the chapter “Window Manager” in Inside Macintosh: Macintosh Toolbox Essentials for information about creating, positioning, and sizing your application windows, and see the chapter “Dialog Manager” for information about creating and positioning alert and dialog boxes.
Users indirectly inform the Display Manager of changes they wish to make to their display environment by using the Monitors control panel or by adding and removing additional displays. The Monitors control panel in turn calls the Display Manager to change the display environment. The Display Manager sends an Apple event—the Display Notice event—to notify applications that it has changed the display environment. For more information about the Monitors control panel, see the chapter “Control Panels” in Inside Macintosh: More Macintosh Toolbox. Apple events are described in detail in Inside Macintosh: Interapplication Communication.
After the user changes the display environment, the Display Manager generates an update event to notify all current applications to update their windows. The chapter “Window Manager” in Inside Macintosh: Macintosh Toolbox Essentials explains how to handle update events for windows.
The Display Manager provides your application with functions that obtain GDevice records for the video devices controlling the displays connected to the user’s computer system. When repositioning a window, for example, your application can use the GDevice records stored in the device list to determine which video device supports the largest display area or the greatest pixel depth. The chapter “Graphics Devices” in Inside Macintosh: Imaging With QuickDraw describes GDevice records and the device list.
The next section, “About the Display Manager,” explains the capabilities of the Display Manager and describes its default behavior when repositioning windows. Read “About the Display Manager” to determine whether your application needs to perform its own window positioning or sizing. If your application needs to perform its own window management in a changing environment, read “Using the Display Manager,” which begins on page 1-17; “Using the Display Manager” discusses how your application can
n determine when the user has changed the display environment
n manage its windows accordingly
About the Display Manager
The Display Manager is a set of system software functions that support dynamic changes to the arrangement and display modes of the displays attached to a user’s computer. (This book uses the term displays to represent output devices—such as video monitors and flat-panel displays—on which applications can show interactive visual information to the user. A video device is the hardware, such as the plug-in video card or the built-in video interface, that controls a display.)
Display Manager functions are used mostly by the Monitors control panel. After opening the Monitors control panel, the user can choose to
n move displays
n switch multiple-resolution displays to use higher or lower screen resolutions
n move the menu bar from one display to another
n select different pixel depths for video devices that support multiple depths
For example, the user of a PowerBook computer can use its external video port to attach a second display. After the user opens the Monitors control panel as shown in Figure 1-1, the user can move the menu bar from one display to another. When the user closes the Monitors control panel, the menu bar immediately moves to the user’s desired location without the user restarting the computer.
Figure 1-1
The Monitors control panel
The user can also add or remove displays without restarting the computer. For example, a user can attach an external monitor to a sleeping PowerBook computer, wake the computer, and use both the external and built-in displays. If the user puts the PowerBook computer to sleep, detaches the external monitor, then wakes the computer, the Display Manager automatically moves windows that had appeared on the external monitor onto the PowerBook built-in display.
Window Repositioning by the Display Manager
A user finds that windows may move from one display to another under any one of three circumstances.
n The Display Manager moves windows after the user removes a display; this allows the user to see windows that had previously appeared on the disconnected display.
n The Display Manager moves windows if the user switches a display to use a lower screen resolution; this allows the user to find windows that would otherwise disappear because of the reduced size of the desktop.
n Windows follow the menu bar when the user moves the menu bar from one display to another.
The Display Manager usually does not move any windows when the user adds a display. The Display Manager never resizes windows.
After the user reduces the display area (such as by removing a display), the Display Manager checks whether any open windows no longer appear on a display. If so, the Display Manager automatically repositions windows of type dBoxProc (that is, alert boxes and modal dialog boxes) so that the lower-left corners of the windows appear onscreen. This gives users access to the area where the OK and Cancel buttons normally should be. For windows of all other types, the Display Manager moves them by the smallest amount necessary for their title bars to appear on the next closest display.
You may need or want your application to perform its own window positioning under various circumstances, such as when
n your application benefits by displaying windows and their contents on the display controlled by the video device with the greatest pixel depth
n your application benefits by displaying and resizing windows on the largest available display
n your application uses nonstandard window definition procedures that draw windows lacking title bars; examples of these types windows include fixed-sized windows without title bars (games often use such windows), tool palettes with drag regions on the left sides of their windows, and floating windows
The next several sections illustrate the default window positioning behaviors of the Display Manager.
When the User Removes a Display
When a user removes a display, the Display Manager moves the windows that had appeared on the disconnected display to the next closest display.
For an alert or modal dialog box, the Display Manager attempts to center its window on the next closest display. If the alert or modal dialog box is larger than the screen, the Display Manager aligns its lower-left corner with the lower-left corner of the next closest display, thereby providing access to the area of the alert or modal dialog box where the OK and Cancel buttons should be.
For any other type of window, the Display Manager assumes that the window has a standard title bar. As illustrated in Figure 1-2 and Figure 1-3, the Display Manager then moves the window to the closest display by the shortest distance necessary to show the entire title bar.
Figure 1-2 Default window repositioning when the user removes the display on the right
As shown in Figure 1-3, the content region of the window may still lie offscreen; but for a standard window, the user has access to the drag region of the title bar and to the zoom box. The user can therefore easily move the entire window onto the screen. To allow users easier window sizing when only the title bar appears, your application should always include a zoom box in its windows by creating them with the zoomDocProc window type.
If the window is wider than the screen, the Display Manager fits onscreen the area in the title bar where the close box should appear.
Figure 1-3 Default window repositioning when the user removes the bottom display
Display Manager Problems Moving Windows
When repositioning any window other than type dBoxProc, the Display Manager assumes that the window has a standard title bar and moves the window to the closest display so that the title bar appears to the user. However, if the window does not have a title bar, the Display Manager may move the window to a position where the user cannot see it.
For example, on the left side of Figure 1-4 a window containing a tool palette and a nonstandard drag region appears in the lower display. When the user removes the lower display, as shown in the right side of the figure, the Display Manager moves the tool palette onto the main screen by the shortest distance necessary to display a standard title bar for the window. However, the window does not have a standard title bar, and so no part of the window appears onscreen. Applications that use windows without standard title bars must reposition their own windows as described in “Using the Display Manager” beginning on page 1-17.
Figure 1-4 A problem with repositioning a nonstandard window
Note
The Display Manager makes no attempt to stack or tile windows so that the user can see all of their titles bars simultaneously. Multiple windows that have been repositioned by the Display Manager may obscure each other’s title bars.u
The Display Manager never resizes windows. Because of this, fixed size windows can present a problem. If a fixed size window appears on a large display, and the user removes that display, only part of the window appears when the Display Manager repositions it on a smaller display. Figure 1-5 illustrates how the Display Manager might reposition the window of a game that draws into a fixed size window.
Figure 1-5
Default repositioning of a fixed-sized window
When the user adds a display, the Display Manager does not move any windows to that display. For example, in Figure 1-6 either the user or the application must move the window on the main screen to the display added on the right. If your application works best on the largest available screen or on the one displaying the greatest number of colors, you may want your application to move its windows to the added display.
Figure 1-6 Default window positioning when the user adds a display
When the User Moves the Menu Bar
On a computer with multiple screens, the user can use the Monitors control panel to change the main screen—that is, the one that contains the menu bar. Color QuickDraw maps the (0,0) origin point of the global coordinate system to the main screen’s upper-left corner, and other screens are positioned adjacent to it. The Window Manager automatically maintains window positions according to this global coordinate system.
When the user changes the main screen, the upper-left corner of the new main screen becomes the (0,0) origin point of QuickDraw’s global coordinate system, and all windows initially maintain their position relative to this new origin point. When a user moves the menu bar, the user sees the windows that had appeared beneath the menu bar on one display move to the display that now contains the menu bar.
Figure 1-7 Default window positioning when the user moves the menu bar
For example, the top of Figure 1-7 shows a window on the left display. The left display is the main screen, and the upper-left corner of the window is positioned at coordinates (50,50) on the global coordinate system. At the bottom of the figure, the user moves the menu bar to the right display. The window retains its upper-left coordinates of (50,50), but because the (0,0) origin of the global coordinate system has moved to the right screen, the window now appears in the right display.
If the Display Manager finds that any windows move offscreen after the user moves the menu bar, the Display Manager repositions the windows as previously described—that is, it tries to move the title bar onto the closest screen or it tries to center the alert or modal dialog box on the closest screen.
Display Modes
The Display Manager allows users to choose from the various display modes available on their displays. A display mode is a combination of several interrelated capabilities that can be altered using the Display Manager to affect the display. A display mode is characterized by
n the screen resolution, which determines the number of pixels that appear on the display screen
n the horizontal and vertical scan timings in use by the display
n the display’s refresh rate
In addition to these capabilities, a display mode may also support multiple pixel depths, which determine the number of colors available on the display. The pixel depths available for a display mode are referred to as depth modes, and in various Display Manager and Slot Manager data structures, depth modes are represented by constants or by their values from an enumerated list. A depth mode also called a video mode.
Single-resolution grayscale or color monitors support multiple pixel depths only. Some multiple-resolution displays, such as some flat panel displays on PowerBook computers, support display modes that change only the screen resolution and the pixel depth. For example, by choosing a lower screen resolution, a color PowerBook user with limited RAM can set the display to show a greater number of colors. Multiple-scan displays, however, are also capable of operating at multiple horizontal and vertical scan timings and at different refresh rates.
For example, a multiple-scan display might support display modes with screen resolutions of 640 by 480 pixels and 1152 by 870 pixels. The left side of Figure 1-8 illustrates a multiple-scan display operating at a screen resolution of 640 by 480 pixels. The right side of the figure illustrates the same display after it has been switched to a screen resolution of 1152 by 870 pixels.
Figure 1-8 Lower and higher screen resolutions on a multiple-scan monitor
When editing a bitmap image with a paint application, a user might wish to use the lower screen resolution, which—compared to the higher resolution—displays fewer pixels on the screen but displays them at a larger size. When using a spreadsheet application, however, the user might then want to switch to the higher resolution to increase the number of onscreen pixels and thereby view a greater number of cells in a spreadsheet.
To change the screen resolution, the user opens the Monitors control panel and selects the display mode for that resolution. The Display Manager then sends the video device driver a control request to switch the display to the newly selected display mode.
As shown in Figure 1-9, all required display modes appear when the user opens the Monitors control panel. For a particular type of display (for example, a 21-inch video monitor), a required display mode is one that Apple requires the display to support. A multiple-scan display must support several required display modes, one of which is designated to be the default display mode. The default display mode appears the first time a user turns on a display. For example, the first time a user connects and starts a 21-inch video monitor, it should use a mode displaying 1152 by 870 pixels. However, a 21-inch multiple-scan display is also required to support display modes with resolutions of 640 by 480 pixels, 832 by 624 pixels, and 1024 by 768 pixels, which the user can select with the Monitors control panel.<<Get up-to-date, grayscale screen shot from a multimode monitor>>
Figure 1-9 Choosing a required display mode from the Monitors control panel
In addition to its required display modes, a display may also support additional display modes, which are called optional display modes. As shown in Figure 1-10, optional display modes appear when the user holds the Option key and clicks the Options button in the Monitors control panel. <<Get up-to-date, grayscale screen shot from a multimode monitor>>
Figure 1-10
Choosing an optional display mode from the Monitors control panel
After the user selects an optional display mode, the Display Manager asks the device driver to switch to that display mode, and the Monitors control panel displays a confirmation dialog box asking whether the mode works. If the mode does not work, the user may not be able to see the dialog box, in which case pressing Command-period, Escape, Return, or Enter all cause the Display Manager to revert to the previous display mode. If within 6 seconds the user does not click a button in the dialog box or press any of these keys, the Display Manager reverts to the previous display mode.
Table 1-1 shows the screen resolutions and scan timings for the default, required, and optional display modes of several Apple displays.
Table 1-1 Characteristics of the display modes for several Apple displays
Display type Screen resolution and scan timing of default mode Screen resolutions and scan timings of other required modes Screen resolutions and scan timings of optional modes
Multiple-scan type 1 640 ¥ 480 pixels at 67 Hz
(e.g., 13-inch display) 832 ¥ 624 pixels at 75 Hz 512 ¥ 384 pixels at 60 Hz
Multiple-scan type 2 832 ¥ 624 pixels at 75 Hz
(e.g., 16-inch display) 640 ¥ 480 pixels at 67 Hz
1024x768 pixels at 75 Hz
Multiple-scan type 3 1152 ¥ 870 pixels at 75 Hz
(e.g., 21-inch display) 640 ¥ 480 pixels at 67 Hz
832 ¥ 624 pixels at 75 Hz
1024 ¥ 768 pixels at 75 Hz
VGA 640 ¥ 480 pixels at 60 Hz 800 ¥ 600 pixels
at 56 Hz (i.e., SVGA)
1024 ¥ 768 pixels
at 60 Hz (i.e., VESA 1K-60Hz)
1024 ¥ 768 pixels
at 70 Hz (i.e., VESA 1K-70Hz)
Full-page portrait 640 ¥ 870 pixels at 75 Hz 640 ¥ 818 pixels at 75 Hz
Using Display Manager functions, your application can change the display mode and the pixel depth of any display for the user, but your application should do so only with the consent of the user. The Monitors control panel is the user interface for changing the pixel depth, color capabilities, and positions of video devices. Because the user can control the capabilities of the video devices, your application should be flexible: although it may have a preferred pixel depth, your application should do its best to accommodate less than ideal conditions.
However, if your application must have a specific pixel depth, or a particular screen resolution, it can display a dialog box that offers the user a choice between changing to that depth or canceling display of the image. This dialog box saves the user the trouble of going to the Monitors control panel before returning to your application. (See the chapter “Dialog Manager” in Inside Macintosh: Macintosh Toolbox Essentials for more information about creating and using dialog boxes.) Your application can then use Display Manager functions to change the display mode or pixel depth of a display.
Video Mirroring
PowerBook computers support video mirroring, which duplicates the windows, menu bar, and desktop from the main screen onto another display. Video mirroring is helpful to a user who, for example, has prepared a presentation on a PowerBook computer and wants to show the presentation to an audience viewing a larger display that is also attached to the PowerBook. The user typically chooses to mirror one display on another by using the PowerBook control strip.
Figure 1-11
Video mirroring
Your application should not draw into the menu bar area on a display that mirrors the main screen. As on the main screen, the menu bar on the mirrored display may otherwise overlap part of your window. To determine whether video mirroring is on, you can use the DMIsMirroringOn function (which is described on page 1-43). After calling the QuickDraw function GetMainDevice (described in the chapter “Graphics Devices” in Inside Macintosh: Imaging With QuickDraw), you can use the GetNextMirrorDevice (described on page 1-35) to determine which device is mirrored to the main screen.
IMPORTANT
To determine the current menu bar height, always use the GetMBarHeight function, which is described in the chapter “Menu Manager” in Inside Macintosh: Macintosh Toolbox Essentials.u
Your application should leave control of video mirroring to the user. However, if video mirroring is useful for your application (for example, if your application displays onscreen presentations), you might provide a control so that the user can switch to video mirroring directly from your application. In this case, the DMMirrorDevices function, described on page 1-52, is useful for switching video mirroring on, and DMUnmirrorDevice function, described on page 1-53, is useful for switching it off again.
Using the Display Manager
The previous section, “About the Display Manager,” explains how the Display Manager automatically repositions windows if necessary to ensure that windows are accessible when the user changes the display environment. If the Display Manager moves windows in a manner inappropriate for your application, your application should reposition them instead. Applications that use only the standard window definition functions provided by the Window Manager generally do not need to use the Display Manager.
However, you may need or want your application to perform its own window positioning under various circumstances, such as when
n your application benefits by displaying windows and their contents on the display controlled by the video device with the greatest pixel depth
n your application benefits by displaying windows on the largest available display
n your application uses nonstandard window definition procedures that draw windows lacking title bars; examples of these types windows include fixed-sized windows without title bars (games often use such windows), tool palettes with drag regions on the left sides of their windows, and floating windows
Note
When necessary, the Display Manager automatically repositions windows of type dBoxProc (that is, alert boxes and modal dialog boxes) so that the lower-left corners of the windows appear onscreen. This gives users access to the area where the OK and Cancel buttons should be.u
In addition, your application should respond to Display Manager changes if your application relies on display information that it stores internally. For example, if your application caches display positions, GDevice records for displays other than the main screen, or the value in the screenBits.bounds field of the screenBits global variable, this information may become invalid after the user changes the display configuration. Therefore, your application should update its internal values accordingly after a display configuration change.
The Display Manager is available on all Power Macintosh computers and on color-capable Macintosh computers running system software version 7.5. To determine whether the Display Manager is available, use the Gestalt function with the gestaltDisplayMgrAttr selector. Test the bit field indicated by the gestaltDisplayMgrPresent constant in the response parameter. If the bit is set, then the Display Manager is present.
gestaltDisplayMgrPresent = 0, /* this bit is set if
Display Manager is
present */
Presence of the Display Manager does not guarantee that a computer also supports video mirroring. As of System Software version 7.5, only PowerBook computers support video mirroring. To determine whether QuickDraw supports video mirroring on the user’s computer system, use the DMQDIsMirroringCapable function, which is described on page 1-41.
Handling Events in Response to Display Manager Changes
Users indirectly inform the Display Manager of changes they wish to make to their display environment by using the Monitors control panel, or by attaching or removing additional displays. The Display Manager in turn sends an Apple event—the Display Notice event—to notify applications that the display environment has changed.
After changing the display environment, the Display Manager also generates an update event to notify all current applications to update their windows.
Your application should always handle update events for its windows. However, your application needs to respond to the Display Notice event only if your application repositions its own windows, uses nonstandard windows, or must update any display information that it stores internally. (For information about updating the content regions of windows in response to update events, see the chapter “Window Manager” in Inside Macintosh: Macintosh Toolbox Essentials.)
To receive the Display Notice event informing you of changes to the user’s display configuration, you must either
n handle the Display Notice event as a high-level event in your application’s normal event loop; or
n use the DMRegisterNotifyProc function to register a procedure that handles the Display Notice event as soon as the Display Manager issues it
If you write a utility—such as a control panel—that doesn’t handle events through a normal event loop, or if you want your application to handle the Display Notice event as soon as it’s issued instead of waiting for it to appear in the event queue, you should use the latter approach.
Here is a summary of the Display Notice event (remember that you must use Apple Event Manager functions to obtain the information contained in Apple events such as this):
Display Notice—respond to display configuration changes
Event class kCoreEventClass
Event ID kAESystemConfigNotice
Required parameter
Keyword: kAEDisplayNotice
Descriptor type: AEDesc
Data: A list of descriptor records, each specified by the keyword kDisplayID. Each kDisplayID descriptor record contains information about a video device attached to the user’s system. Within each kDisplayID descriptor record are a pair of additional keyword-specified descriptor records: keyDisplayOldConfig and keyDisplayNewConfig. A description of the video device’s previous state is saved in the keyDisplayOldConfig descriptor record, and a description of the video device’s current state is saved in the keyDisplayNewConfig descriptor record.
These keyword-specified descriptor records are described and listed in Table 1-2. See the chapter “Graphics Devices” in Inside Macintosh: Imaging With QuickDraw for further information about the fields of the GDevice record cited in the table.
Requested action Ensure that all windows appear to the user, and update any necessary display information that your application or utility stores internally.
Table 1-2
Keyword-specified descriptor records containing display information in the Display Notice event
Keyword Value Type Description
keyDeviceDepthMode 'dddm' typeLongInteger The depth mode for the video device; that is, the value of the gdMode field in the GDevice record for the device
keyDeviceFlags 'dddf' typeShortInteger The attributes for the video device as maintained in the gdFlags field of the GDevice record for the device
keyDeviceRect 'dddr' typeQDRectangle The boundary rectangle of the video device; that is, the value of the gdRect field in the GDevice record for the device
keyDisplayComponent 'dmdc' typeLongInteger Reserved for future use
keyDisplayDevice 'dmdd' typeLongInteger A handle to the GDevice record for the video device
keyDisplayFlags 'dmdf' typeLongInteger Reserved for future use
keyDisplayID 'dmid' typeLongInteger The display ID for the video device
keyDisplayMode 'dmdm' typeLongInteger The sResource number from the video device for this display mode
keyDisplayModeReserved 'dmmr' typeLongInteger Reserved for future use
keyDisplayReserved 'dmdr' typeLongInteger Reserved for future use
keyDMConfigFlags 'dmcf' typeLongInteger Reserved for future use
keyDMConfigReserved 'dmcr' typeLongInteger Reserved for future use
keyDMConfigVersion 'dmcv' typeLongInteger The version number for this Display Notice event
keyPixMapAlignment 'dppa' typeLongInteger Reserved for future use
keyPixMapCmpCount 'dpcc' typeShortInteger The number of components used to represent a color for a pixel; that is, the value of the cmpCount field in the PixMap record for the GDevice record for the device
keyPixMapCmpSize 'dpcs' typeShortInteger The size in bits of each component for a pixel; that is, the value of the cmpSize field in the PixMap record for the GDevice record for the device
keyPixMapColorTableSeed 'dpct' typeLongInteger The value of the ctSeed field of the ColorTable record for the PixMap record for the GDevice record for the video device
keyPixMapHResolution 'dphr' typeFixed The horizontal resolution of the pixel image in the PixMap record for the GDevice record for the video device
keyPixMapPixelSize 'dpps' typeShortInteger Pixel depth for the device; that is, the value of the pixelSize field in the PixMap record for the GDevice record for the video device
keyPixMapPixelType 'dppt' typeShortInteger The storage format for the pixel image on the device; that is, the value of the pixelType field in the PixMap record for the GDevice record for the video device
keyPixMapRect 'dpdr' typeQDRectangle The boundary rectangle into which QuickDraw can draw; that is, the bounds field in the PixMap record for the GDevice record for the video device
keyPixMapReserved 'dppr' typeLongInteger Reserved for future use
keyPixMapResReserved 'dprr' typeLongInteger Reserved for future use
keyPixMapVResolution 'dpvr' typeFixed The vertical resolution of the pixel image in the PixMap record for the GDevice record for the video device
Handling the Display Notice Event as a High-Level Event
To handle the Display Notice event as a high-level event like any other Apple event, you need to
n set the isHighLevelEventAware bit in your application’s 'SIZE' resource to indicate that your application supports high-level events (in which case your application must also support the four required Apple events, as described in the chapter “Responding to Apple Events” in Inside Macintosh: Interapplication Communication.)
n include code to handle high-level events in your main event loop (as illustrated in Listing 1-1)
n write a routine that handles the Display Notice event (as illustrated in Listing 1-2)
n use the AEInstallEventHandler function to install the entry for handling the Display Notice event in your application’s Apple event dispatch table
If you want your application to handle all window positioning itself (that is, if you do not want the Display Manager to automatically move any of your windows in the manner illustrated in “About the Display Manager” beginning on page 1-6), you should also set the isDisplayManagerAware bit in the 'SIZE' resource.
Listing 1-1 illustrates how your application can handle Apple events in its event loop. The AEProcessAppleEvent function, which sends Apple events to your Apple event handler, is described in Inside Macintosh: Interapplication Communication.
Listing 1-1 Handling Apple events in the event loop
void MyDoEvent(EventRecord *event)
{
short part, err;
WindowPtr window;
char key;
switch ( event->what ) {
/* here, handle null, mouse down, key down, update, and
other necessary events */
case kHighLevelEvent:
DoHighLevelEvent(event);
break;
}
}
void DoHighLevelEvent(EventRecord *event)
{
OSErr myErr;
/* handling only Apple-event types of high-level events */
myErr = AEProcessAppleEvent(event);
}
Your application must use the AEInstallEventHandler function to add an entry to your application’s Apple event dispatch table. This entry is the function that responds to the Display Notice event. For example, the following code fragment illustrates how to use AEInstallEventHandler to install an application-defined function called DoAEDisplayUpdate.
err = AEInstallEventHandler (kCoreEventClass,
kAESystemConfigNotice,
(ProcPtr)DoAEDisplayUpdate, 0, false);
Listing 1-2 shows an application-defined function called DoAEDisplayUpdate that uses Apple Event Manager functions to obtain information about the various video devices reported by the Display Notice event. The DoAEDisplayUpdate uses this information to update its internal data structures for its windows and then calls another application-defined function that ensures that its windows are displayed optimally in the new configuration environment.
Listing 1-2 Responding to the Display Notice event
/* update internal info about the gdRects for the devices */
MyUpdateWindowStructures(oldRect, newRect);
count--;
}
<<shouldn’t we dispose of of all AEDescList, AEDescList, AERecord, and
AEDesc structures here? as in myErr = AEDisposeDesc(&DisplayList); >>
MyDisplayWindows(); /* move and resize windows as necessary */
return (noErr);
}
Handling the Display Notice Event Outside of an Event Loop
As previously state, you may want your application to handle the Display Notice event as soon as it’s issued instead of waiting for it to appear in the event queue. You can use the DMRegisterNotifyProc function, described on page 1-61, to register a procedure to which the Display Manager directly sends the Display Notice event. By using DMRegisterNotifyProc and by not setting the isHighLevelEventAware bit in the 'SIZE' resource, you cause the Display Manager to send a Display Notice event directly to your handling procedure; your application or utility then receives no high-level Display Notice event.
Your Display Notice event-handling procedure should take one parameter: the Apple event describing the changes made to the display configuration.
If you want your application to handle all window positioning itself (that is, if you do not want the Display Manager to automatically move any of your windows as described in “About the Display Manager” beginning on page 1-6), be sure to set the isDisplayManagerAware bit in the 'SIZE' resource.
To remove your Display Notice event-handling procedure, use the DMRemoveNotifyProc function, which is described on page 1-62
Managing Windows In Response to the Display Notice Event
Using the Monitors control panel, the user can switch displays to use a different display mode and to change the display configurations by moving displays, moving the menu bar from one display to another, and selecting different pixel depths for video devices that support multiple depths. When your application receives the Display Notice event as described in the previous section, your application must determine whether it needs to reposition and, optionally, resize its windows.
Listing 1-3 illustrates how an application can check whether its nonstandard window appears onscreen after Display Manager configuration changes have occurred. In this example, the application has a window with a title bar on its left side, as shown in the tool palette illustrated in Figure 1-4 on page 1-10. After receiving the Display Notice event as shown in Listing 1-2 on page 1-24, the application calls its MyDisplayWindows function, which in turn calls its MyMakeToolWindowVisible function. If MyMakeToolWindowVisible determines that the nonstandard title bar does not appear on any displays (in which case the user cannot move the window), MyMakeToolWindowVisible moves the entire window to the main screen where the user has access to the window.
Listing 1-3 Ensuring a nonstandard window appears onscreen
MyKeepWindowOnscreen(window, nil); /* handle other nonstandard window
variants here */
}
return noErr;
}
Your application may find it useful to resize a window after moving it, or to optimize its color for its newly configured video device. You can use Display Manager functions to determine the characteristics of video devices, as explained in the next section.
Determining the Characteristics of the Video Devices
To determine the characteristics of available vide devices, your application can use the DMGetFirstScreenDevice function to obtain a handle to the GDevice record for the first video device in the device list. The DMGetFirstScreenDevice function is described in detail beginning on page 1-33. The DMGetFirstScreenDevice function is similar to the QuickDraw function GetDeviceList (which is described in the chapter “Graphics Devices” in Inside Macintosh: Imaging With QuickDraw), except that when returning GDevice records, GetDeviceList does not distinguish between the GDevice records for video devices and the GDevice records associated with no video devices. (For example, if system software uses DMDisableDisplay to disable the last remaining device in the device list, then DMDisableDisplay inserts into the device list a GDevice record that is not associated with any video device. The DMGetFirstScreenDevice function will not return this GDevice record, but GetDeviceList might.)
After using the DMGetFirstScreenDevice function to obtain a handle to the first GDevice record for a display in the device list, your application can use the DMGetNextScreenDevice function to loop through all of the video devices in the device list. The DMGetNextScreenDevice function is similar to the QuickDraw function GetNextDevice, except that when returning GDevice records, GetNextDevice does not distinguish between the GDevice records for video devices and the GDevice records associated with no video devices.
Another important difference between these two Display Manager functions (DMGetFirstScreenDevice and DMGetNextScreenDevice) and their related QuickDraw functions (GetDeviceList and GetNextDevice) is that with both Display Manager functions, your application can additionally specify that the Display Manager return handles only to active video devices. (An active device is a video device whose display area is included in the user’s desktop; the display area of an inactive device does not appear on the user’s desktop.)
To get a handle to the GDevice record for a video device that mirrors another, your application can use the DMGetNextMirroredDevice function.
Your application can pass the GDevice handle returned for any of these video devices to a QuickDraw function like TestDeviceAttribute or HasDepth to determine various characteristics of the video device, or your application can examine the gdRect field of the GDevice record to determine the dimensions of the screen it represents.
The chapter “Window Manager” in Inside Macintosh: Macintosh Toolbox Essentials provides code samples illustrating how to create, draw, zoom, and resize windows. Some of these code samples use the Color QuickDraw functions GetDeviceList and GetNextDevice. Instead of these functions, your application can use the Display Manager functions DMGetFirstScreenDevice and DMGetNextScreenDevice, respectively, to simplify its window management tasks.
Macintosh system software uses the DMCheckDisplayMode function to determine whether a particular display mode and pixel depth are supported by a video device. Typically, your application doesn’t need to know whether a display mode is supported, but rather, only whether a specific pixel depth is supported, in which case your application can use the Color QuickDraw function HasDepth. The DMCheckDisplayMode function is described on page 1-38 for completeness. The HasDepth function is described in the chapter “Graphics Devices” in Inside Macintosh: Imaging With QuickDraw.
To determine whether QuickDraw supports video mirroring on the user’s computer system, your application can use the DMQDIsMirroringCapable function. Your application can use the DMCanMirrorNow function to determine whether video mirroring can be activated. And to determine whether the user’s computer system currently uses video mirroring, your application can use the DMIsMirroringOn function.
Finally, your application can use the DMGetDisplayIDByGDevice function to determine the display ID for a video device. A display ID is a long integer used by the Display Manager to uniquely identify a video device. Associating a display by its display ID is helpful when using functions such as DMRemoveDisplay that could possibly change the GDevice record associated with a video device. You can first determine the display ID for a device by using the DMGetDisplayIDByGDevice function, which is described on page 1-36. To later retrieve that device’s GDevice record after calling various Display Manager functions, your application can use the DMGetGDeviceByDisplayID function, which is described on page 1-37.
Setting Configurations and Display Modes for Video Devices
The Monitors control panel is the user interface for changing the pixel depth, color capabilities, and positions of video devices. Because the user can control the capabilities of the video devices, your application should be flexible: although it may have a preferred pixel depth, for example, your application should do its best to accommodate less than ideal conditions.
Your application can use Display Manager functions to change the display mode and display configuration of the user’s video devices, but your application should do so only with the consent of the user.
If your application must have a specific pixel depth, for example, it can display a dialog box that offers the user a choice between changing to that depth or canceling display of the image. This dialog box saves the user the trouble of going to the Monitors control panel before returning to your application. (See the chapter “Dialog Manager” in Inside Macintosh: Macintosh Toolbox Essentials for more information about creating and using dialog boxes.) If it is absolutely necessary for your application to draw on a video device of a specific pixel depth, your application can then use either the SetDepth function (described in the chapter “Graphics Devices” in Inside Macintosh: Imaging With QuickDraw) or the DMSetDisplayMode function, described on page 1-45.
With the possible exception of the DMSetDisplayMode function and the DMMirrorDevices and DMUnmirrorDevice functions, applications should generally never need to use any of the Display Manager functions that change the user’s display configuration. However, beginning on page 1-44 they are described for completeness, in case you find a compelling need for your application to change the user’s display configuration. If your application must use multiple Display Manager calls that configure the user’s displays, your application should first use the DMBeginConfigureDisplays function to postpone Display Manager configuration checking, the rebuilding of desktop regions, and Apple event notification of Display Manager changes. When finished configuring the user’s displays, use the DMEndConfigureDisplays function. Using DMBeginConfigureDisplays and DMEndConfigureDisplays allows your application to wait until it’s made all display changes before managing its windows in response to a single Display Notice event.
The following list explains the Display Manager functions that change the user’s display configuration.
n The DMSetDisplayMode function, described on page 1-45, sets the pixel depth or the display mode for a device.
n The DMMirrorDevices function, described on page 1-52, turns on video mirroring.
n The DMUnmirrorDevice function, described on page 1-53, turns off video mirroring.
n The DMMoveDisplay function, described on page 1-47, moves the boundary rectangle for a device within the QuickDraw global coordinate plane.
n The DMDisableDisplay function, described on page 1-48, makes a video device inactive by removing it from the desktop.
n The DMEnableDisplay function, described on page 1-49, reactivates a display that was made inactive with the DMDisableDisplay function.
n The DMSetMainDisplay function, described on page 1-51, sets a display to be the main screen.
n The DMBlockMirroring function, described on page 1-54, disables video mirroring.
n The DMUnblockMirroring function, described on page 1-54, reenables video mirroring that was disabled with the DMBlockMirroring function.
Display Manager Reference
The section describes the constants and functions defined for your application’s use by the Display Manager.
Constants
The section describes the constants defined for your application’s use by the Display Manager.
Display Notice Event Keywords
The Display Manager sends an Apple event—the Display Notice event—to notify applications that it has changed the display environment. The keywords that specify the Display Notice event and its descriptor records are described here.
#define kAESystemConfigNotice 'cnfg'
#define kAEDisplayNotice 'dspl'
#define keyDisplayOldConfig 'dold'
#define keyDisplayNewConfig 'dnew'
#define keyDMConfigVersion 'dmcv'
#define keyDMConfigFlags 'dmcf'
#define keyDMConfigReserved 'dmcr'
#define keyDisplayID 'dmid'
#define keyDisplayComponent 'dmdc'
#define keyDisplayDevice 'dmdd'
#define keyDisplayFlags 'dmdf'
#define keyDisplayMode 'dmdm'
#define keyDisplayModeReserved 'dmmr'
#define keyDisplayReserved 'dmdr'
#define keyDeviceFlags 'dddf'
#define keyDeviceDepthMode 'dddm'
#define keyDeviceRect 'dddr'
#define keyPixMapRect 'dpdr'
#define keyPixMapHResolution 'dphr'
#define keyPixMapVResolution 'dpvr'
#define keyPixMapPixelType 'dppt'
#define keyPixMapPixelSize 'dpps'
#define keyPixMapCmpCount 'dpcc'
#define keyPixMapCmpSize 'dpcs'
#define keyPixMapAlignment 'dppa'
#define keyPixMapResReserved 'dprr'
#define keyPixMapReserved 'dppr'
#define keyPixMapColorTableSeed 'dpct'
Constant descriptions
kAESystemConfigNotice
Keyword for the Event ID for Display Notice event
kAEDisplayNotice
Keyword for required parameter to Display Notice event
keyDisplayOldConfig
Keyword for the descriptor record describing the video device’s previous state
keyDisplayNewConfig
Keyword for the descriptor record describing the video device’s new state
keyDMConfigVersion
Keyword for the descriptor record describing the version number for this Display Notice event
keyDMConfigFlags
Reserved for future use
keyDMConfigReserved
Reserved for future use
keyDisplayID Keyword for the descriptor record describing the display ID for the video device
keyDisplayComponent
Reserved for future use
keyDisplayDevice
Keyword for the descriptor record containing a handle to the GDevice record for the video device
keyDisplayFlags Reserved for future use
keyDisplayMode Keyword for the descriptor record containing the sResource number from the video device for this display mode
keyDisplayModeReserved
Reserved for future use
keyDisplayReserved
Reserved for future use
keyDeviceFlags Keyword for the descriptor record describing the attributes for the video device as maintained in the gdFlags field of the GDevice record for the device
keyDeviceDepthMode
Keyword for the descriptor record describing the depth mode for the video device; that is, the value of the gdMode field in the GDevice record for the device
keyDeviceRect Keyword for the descriptor record describing the boundary rectangle of the video device; that is, the value of the gdRect field in the GDevice record for the device
keyPixMapRect Keyword for the descriptor record describing the boundary rectangle into which QuickDraw can draw; that is, the bounds field in the PixMap record for the GDevice record for the video device
keyPixMapHResolution
Keyword for the descriptor record describing the horizontal resolution of the pixel image in the PixMap record for the GDevice record for the video device
keyPixMapVResolution
Keyword for the descriptor record describing the vertical resolution of the pixel image in the PixMap record for the GDevice record for the video device
keyPixMapPixelType
Keyword for the descriptor record describing the storage format for the pixel image on the device; that is, the value of the pixelType field in the PixMap record for the GDevice record for the video device
keyPixMapPixelSize
Keyword for the descriptor record describing the pixel depth for the device; that is, the value of the pixelSize field in the PixMap record for the GDevice record for the video device
keyPixMapCmpCount
Keyword for the descriptor record containing the number of components used to represent a color for a pixel; that is, the value of the cmpCount field in the PixMap record for the GDevice record for the device
keyPixMapCmpSize
Keyword for the descriptor record describing the size in bits of each component for a pixel; that is, the value of the cmpSize field in the PixMap record for the GDevice record for the device
keyPixMapAlignment
Reserved for future use
keyPixMapResReserved
Reserved for future use
keyPixMapReserved
Reserved for future use
keyPixMapColorTableSeed
Keyword for the descriptor record containing the value of the ctSeed field of the ColorTable record for the PixMap record for the GDevice record for the video device
Active Device Only Values
In the activeOnly parameter to the DMGetFirstScreenDevice and DMGetNextScreenDevice functions, you can specify either of two constants representing Boolean values that indicate whether the functions should return a handle to the GDevice record only for an active device or for any device. (The DMGetFirstScreenDevice and DMGetNextScreenDevice functions are described, respectively, on page 1-33 and page 1-34.)
#define dmOnlyActiveDisplays true
#define dmAllDisplays false
Constant descriptions
dmOnlyActiveDisplays
Return a handle to the GDevice record for an active device only
dmAllDisplays Return a handle to the GDevice record for a device, active or not
Switch Flags
In its switchFlags parameter, the DMCheckDisplayMode function returns a pointer to a long integer that specifies flags in two of its bits. The following constants represent bits that are set to 1. (The DMCheckDisplayMode function is described on page 1-38.)
enum {
kNoSwitchConfirmBit = 0,
kDepthNotAvailableBit
};
Constant descriptions
kNoSwitchConfirmBit
It this bit is set, the display mode is a required display mode, which appears in the Monitors control panel without requiring the user to hold the Option key when clicking the Options button.
kDepthNotAvailableBit
If this bit is set, the pixel depth of this device is not available for the specified display mode
Functions
This section describes functions for getting the GDevice records for video devices, determining display modes and display configurations, changing display modes and display configurations, adding and removing video devices from the device list, registering and removing a procedure to receive and process the Display Notice event, and drawing the desktop.
Getting Video Devices
You can use the functions described in this section to obtain handles to the GDevice records or display IDs for video devices.
DMGetFirstScreenDevice
To obtain a handle to the GDevice record for the first video device in the device list, use the DMGetFirstScreenDevice function.
activeOnly A Boolean value indicating whether DMGetFirstScreenDevice should return a handle to the GDevice record for the first active device in the device list or to the first device, active or not. If you supply this parameter with the value true, DMGetFirstScreenDevice returns a handle the first of all active video devices; if you supply the value false, DMGetFirstScreenDevice returns a handle to the first of all video devices. You may also supply one of the following constants in this parameter:
#define dmOnlyActiveDisplays true
#define dmAllDisplays false
DESCRIPTION
The DMGetFirstScreenDevice function returns a handle to the GDevice record for the first video device in the device list. Pass the dmOnlyActiveDisplays constant, or true, in the activeOnly parameter if you want only the first active video device in the device list. If you pass the dmAllDisplays constant, or false, in this parameter, DMGetFirstScreenDevice returns the first video device regardless of whether it is active or inactive.
You can use the DMGetNextScreenDevice function, described next, to loop through all of the video devices in the device list.
The DMGetFirstScreenDevice function is similar to the QuickDraw function GetDeviceList, except that when returning GDevice records, GetDeviceList does not distinguish between inactive and active video devices or between the GDevice records for video devices and the GDevice records associated with no video devices.
SPECIAL CONSIDERATIONS
The DMGetFirstScreenDevice function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
SEE ALSO
The GetDeviceList function is described in the chapter “Graphics Devices” in Inside Macintosh: Imaging With QuickDraw.
DMGetNextScreenDevice
After using the DMGetFirstScreenDevice function to obtain a handle to the first GDevice record in the device list, you can use the DMGetNextScreenDevice function to loop through all of the video devices in the device list.
theDevice A handle to the GDevice record at which you want the search to begin. You can supply the handle returned by the DMGetNextScreenDevice function, which is described in the preceding section, to begin the search and then loop through the rest of the video devices in the device list.
activeOnly A Boolean value indicating whether DMGetNextScreenDevice should return a handle to the GDevice record for the next active device in the device list or to the next device, active or not. If you supply this parameter with the value true, DMGetNextScreenDevice returns a handle the next active video device; if you supply the value false, DMGetNextScreenDevice returns a handle to the next video device, active or not. You may also supply one of the following constants in this parameter:
#define dmOnlyActiveDisplays true
#define dmAllDisplays false
DESCRIPTION
Basing its starting point with the GDevice record that you specify in the parameter theDevice, the DMGetNextScreenDevice function returns a handle to the next GDevice record for a video device in the device list.
If there are no more GDevice records in the list, DMGetNextScreenDevice returns NIL.
The DMGetNextScreenDevice function is similar to the QuickDraw function GetNextDevice, except that when returning GDevice records, GetNextDevice does not distinguish between inactive and active video devices or between the GDevice records for video devices and the GDevice records associated with no video devices.
SPECIAL CONSIDERATIONS
The DMGetNextScreenDevice function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
SEE ALSO
The GetNextDevice function is described in the chapter “Graphics Devices” in Inside Macintosh: Imaging With QuickDraw.
DMGetNextMirroredDevice
To get a handle to the GDevice record for a video device that mirrors another, use the DMGetNextMirroredDevice function.
gDevice A handle to the GDevice record for the video device that is being mirrored.
mirroredDevice
A pointer to the handle to the GDevice record for the video device that displays a mirror image of the device specified in the gDevice parameter.
DESCRIPTION
For the next mirrored device in the device list, the DMGetNextMirroredDevice function returns a pointer to the handle to the GDevice record for that device. Specify the video device being mirrored in the mirroredDevice parameter.
SPECIAL CONSIDERATIONS
As of system software version 7.5, mirroring works only on PowerBook computers, and only for two video devices. To support future releases of system software that may allow mirroring to additional devices, this function supports looping through all devices that mirror the device specified in the mirroredDevice parameter.
The DMGetNextMirroredDevice function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kDMGenErr –6220 Indeterminate error
kDMMirroringNotOn –6225 Video mirroring is not currently enabled
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
kDMSWNotInitializedErr –6227 Used internally by the Display Manager, this error occurs when required pieces of system software are not initialized
kDMDisplayNotFoundErr –6229 There are no GDevice records for displays in the device list
DMGetDisplayIDByGDevice
To obtain the display ID for a video device, use the DMGetDisplayIDByGDevice function.
A handle to the GDevice record for the video device whose display ID you wish to obtain.
displayID A pointer to the display ID returned by the DMGetDisplayIDByGDevice function.
failToMain A Boolean value. If you specify TRUE, and the video device does not have an associated display ID, then DMGetDisplayIDByGDevice returns the display ID of the video device for the main screen. If your application passes FALSE in this parameter and there is no display ID for the display, this function returns the kDMDisplayNotFoundErr result code.
DESCRIPTION
In the displayID parameter, the DMGetDisplayIDByGDevice returns a pointer to the display ID associated with the video device that you specify in the displayDevice parameter.
SPECIAL CONSIDERATIONS
The DMGetDisplayIDByGDevice function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
kDMSWNotInitializedErr –6227 Used internally by the Display Manager, this error occurs when required pieces of system software are not initialized
kDMDisplayNotFoundErr –6229 There are no GDevice records for displays in the device list
DMGetGDeviceByDisplayID
To get a handle to the GDevice record for the video device with a particular display ID, use the DMGetGDeviceByDisplayID function.
displayID The display ID for the video device whose GDevice record you wish to obtain.
displayDevice
A pointer to the handle for the GDevice record returned by the DMGetGDeviceByDisplayID function.
failToMain A Boolean value. If you specify true, and there is no video device associated with the display ID you specify in the displayID parameter, then DMGetGDeviceByDisplayID returns the video device for the main screen. If your application passes false in this parameter and there is no display ID for the display, this function returns the kDMDisplayNotFoundErr result code.
DESCRIPTION
In the displayDevice parameter, the DMGetGDeviceByDisplayID function returns a pointer to a handle to the GDevice record associated with the display ID you specify in the displayID parameter.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
kDMSWNotInitializedErr –6227 Used internally by the Display Manager, this error occurs when required pieces of system software are not initialized
kDMDisplayNotFoundErr –6229 There are no GDevice records for displays in the device list
Determining Display Modes and Display Configurations
Using the functions described in this section, your application can determine the display modes and other display configurations of the user’s system.
DMCheckDisplayMode
Macintosh system software uses the DMCheckDisplayMode function to determine the whether a particular display mode and pixel depth are supported by a video device. Typically, your application doesn’t need to know whether a display mode is supported, but rather, only whether a specific pixel depth is supported, in which case your application can use the Color QuickDraw function HasDepth. The DMCheckDisplayMode function is described here for completeness.
theDevice A handle to the GDevice record for the video device whose display mode you wish to check.
mode The number used by a video device to identify the functional sResource data structure describing a display mode for the device. If you supply the value 0 in this parameter, then DMCheckDisplayMode uses the current display mode. To test for another display mode, supply the slot resource reference number returned by the Slot Manager function SGetSRsrc.
depthMode For the pixel depth for which you are checking (on the device specified in the parameter theDevice using the display mode specified in the mode parameter), a value that identifies its depth mode. Supply a value from the following enumerated list. (To determine whether the depth mode is supported, check the value of the bit represented by the kDepthNotAvailableBit constant in the switchFlags parameter.)
enum {
firstVidMode = 128, /* first depth mode,
representing lowest
supported pixel
depth */
secondVidMode = 129, /* second depth mode,
representing next
highest depth */
thirdVidMode = 130, /* third depth mode,
representing next
highest depth */
fourthVidMode = 131, /* fourth depth mode,
representing next
highest depth */
fifthVidMode = 132, /* fifth depth mode,
representing next
highest depth */
sixthVidMode = 133, /* sixth depth mode,
representing next
highest depth */
};
A depth mode specified by the firstVidMode constant represents the lowest supported pixel depth—typically, 1 bit per pixel. A depth mode specified by the secondVidMode constant represents the next highest supported pixel depth—often, but not necessarily, 2 bits per pixel. If a video device supports 4 bits per pixel instead of 2 as its next highest pixel depth, then its driver uses the secondVidMode constant to represent 4 bits per pixel. In this manner, the remaining constants signifying depth modes specify an ordered set of increasingly higher pixel depths.
switchFlags
A pointer to a long integer that specifies flags in two of its bits. The following constants represent bits that are set to 1.
enum { /* switch flags */
kNoSwitchConfirmBit = 0, /* if set, there is no
need to confirm a
switch to this mode
when using
DMSetDisplayMode */
kDepthNotAvailableBit /* if set, the pixel depth
of this device is not
available in the
specified display
mode */
};
The value represented by the kNoSwitchConfirmBit constant indicates that the display mode is a required display mode, which appears in the Monitors control panel without requiring the user to hold the Option key when clicking the Options button.
The value represented by the kDepthNotAvailableBit constant indicates that the pixel depth is not available for the display mode specified in the depthMode parameter.
reserved Reserved. Always pass the value NIL in this parameter.
modeOk When the DMCheckDisplayMode function returns true as the value pointed to by this parameter, the video device has not deleted this display mode from the slot resource table, and so the user or—if absolutely necessary—your application, can switch the video device to this display mode.
DESCRIPTION
In the switchFlags parameter, the DMCheckDisplayMode function reports whether the pixel depth you specify in the depthMode parameter is supported for the display mode you specify in the mode parameter for the video device you specify in the parameter theDevice.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
SEE ALSO
The Color QuickDraw function HasDepth is described in the chapter “Graphics Devices” in Inside Macintosh: Imaging With QuickDraw. For information about functional sResources and the slot resource table, see the chapter “Slot Manager” in Inside Macintosh: Devices. To change the video device to the display mode reported by DMCheckDisplayMode, system software use the DMSetDisplayMode, which is described on page 1-45.
DMQDIsMirroringCapable
To determine whether QuickDraw supports video mirroring on the user’s system, use the DMQDIsMirroringCapable function.
pascal OSErr DMQDIsMirroringCapable
(Boolean *qdIsMirroringCapable)
qdIsMirroringCapable
A pointer to the value true if video mirroring is supported; otherwise, a pointer to the value false.
DESCRIPTION
The DMQDIsMirroringCapable function sets the value pointed to by the qdIsMirroringCapable parameter to true if QuickDraw supports device mirroring.
SPECIAL CONSIDERATIONS
As of System Software version 7.5, only PowerBook computers support video mirroring.
The DMQDIsMirroringCapable function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
SEE ALSO
To determine whether video mirroring can be activated on the user’s computer system, use the DMCanMirrorNow function, which is described next. To determine whether the user’s system currently uses video mirroring, use the DMIsMirroringOn function, which is described on page 1-43.
DMCanMirrorNow
To determine whether video mirroring can be activated on the user’s computer system, use the DMCanMirrorNow function.
A pointer to a Boolean value; true indicates that mirroring can be activated; false indicates it cannot.
DESCRIPTION
In the value pointed to by the canMirrorNow parameter, the DMCanMirrorNow function reports whether video mirroring can be activated. When the canMirrorNow parameter points to a value of true, then the computer uses a version of QuickDraw that supports video mirroring, has exactly two displays attached, and does not have mirror blocking in effect.
SPECIAL CONSIDERATIONS
As of System Software version 7.5, only PowerBook computers support video mirroring.
The DMCanMirrorNow function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kDMWrongNumberOfDisplays –6222 System software version 7.5 supports video mirroring for only two displays
kDMMirroringBlocked –6223 Video mirroring currently blocked by a call to DMBlockMirroring
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
SEE ALSO
You can use the DMQDIsMirroringCapable function (described on page 1-52) to determine whether the computer uses a version of QuickDraw that supports video mirroring. You can use the DMBlockMirroring function and the DMUnBlockMirroring functions (described on page 1-54 and page 1-55, respectively) to block and unblock video mirroring. To determine whether the user’s computer system currently uses video mirroring, use the DMIsMirroringOn function, which is described next.
DMIsMirroringOn
To determine whether the user’s computer currently uses video mirroring, use the DMIsMirroringOn function.
A pointer to a Boolean value; true indicates that mirroring is on; false indicates it is not.
DESCRIPTION
In the value pointed to by the isMirroringOn parameter, the DMIsMirroringOn function reports whether the user’s computer system currently uses video mirroring. When the isMirroringOn parameter points to a value of true, then mirroring is on.
SPECIAL CONSIDERATIONS
As of System Software version 7.5, only PowerBook computers support video mirroring.
The DMIsMirroringOn function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
Changing Display Modes and Display Configurations
With the possible exception of the DMSetDisplayMode function and the DMMirrorDevices and DMUnmirrorDevice functions, applications should generally never need to use any of the Display Manager functions that change the user’s display configuration. However, all Display Manager functions that change display configurations are described here for completeness, in case you find a compelling need for your application to change the user’s display configuration.
IMPORTANT
If your application uses Display Manager functions to change the display configuration of the user’s video devices, your application should make these changes only with the consent of the user. If your application must have a specific pixel depth, for example, it can display a dialog box that offers the user a choice between changing to that depth or canceling display of the image. u
DMBeginConfigureDisplays
Before using multiple Display Manager calls that configure the user’s displays, use the DMBeginConfigureDisplays function.
A pointer to a handle to internal Display Manager information about the current display state. Passing this handle to additional Display Manager functions causes system software to postpone Display Manager configuration checking, the rebuilding of desktop regions, and Apple event notification of Display Manager changes until your application uses the DMEndConfigureDisplays function.
DESCRIPTION
In the displayState parameter, the DMBeginConfigureDisplays function returns a pointer to a handle to internal Display Manager information about the current display state. If you use more than one Display Manager function that configures the user’s displays, use DMBeginConfigureDisplays first. Then pass the handle pointed to in the displayState parameter instead of nil to subsequent Display Manager functions.
When your application is finished configuring the display environment, use the DMEndConfigureDisplays function, which is described on page 1-55. Using DMBeginConfigureDisplays and DMEndConfigureDisplays allows your application to wait until it’s made all display changes before managing its windows in response to a single Display Notice event.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
DMSetDisplayMode
To set the pixel depth or display mode for a video device, you can use the DMSetDisplayMode function.
theDevice A handle to the GDevice record for the video device whose display mode you wish to set.
mode The number used by a video device to identify the functional sResource data structure describing a display mode for the device. If you supply the value 0 in this parameter, then DMSetDisplayMode uses the current display mode. To specify another display mode, supply the slot resource reference number returned by the Slot Manager function SGetSRsrc.
depthMode Upon input, a pointer to the desired pixel depth for the video device controlling the display. Upon completion, a pointer to the depth mode (also called the video mode) describing the pixel depth for the display mode set by your application.
You must pass an initial value in this parameter. If you pass 0 here, DMSetDisplayMode attempts to keep the current depth. If you pass 1, 2, 4, 8, 16, or 32, DMSetDisplayMode attempts to set the device to use your specified pixel depth. If you supply a value of 128 or greater, then DMSetDisplayMode sets the depth to the depth mode represented by the values and constants in the following list:
enum {
firstVidMode = 128, /* first depth mode,
representing lowest
supported pixel
depth */
secondVidMode = 129, /* second depth mode,
representing next
highest depth */
thirdVidMode = 130, /* third depth mode,
representing next
highest depth */
fourthVidMode = 131, /* fourth depth mode,
representing next
highest depth */
fifthVidMode = 132, /* fifth depth mode,
representing next
highest depth */
sixthVidMode = 133, /* sixth depth mode,
representing next
highest depth */
};
A depth mode specified by the firstVidMode constant represents the lowest supported pixel depth—typically, 1 bit per pixel. A depth mode specified by the secondVidMode constant represents the next highest supported pixel depth—often, but not necessarily, 2 bits per pixel. If a video device supports 4 bits per pixel instead of 2 as its next highest pixel depth, then its driver uses the secondVidMode constant to represent 4 bits per pixel. In this manner, the remaining constants signifying depth modes specify an ordered set of increasingly higher pixel depths.
Upon completion, DMSetDisplayMode returns a pointer to a value from the list above. The value pointed to in the depthMode parameter identifies the depth mode for the video device controlling the display. This value represents the depth mode closest to the one you requested when calling DMSetDisplayMode.
reserved Reserved; always pass 0 in this parameter.
displayState
To postpone Display Manager configuration checking, the rebuilding of desktop regions, and Apple event notification of Display Manager changes, supply this parameter with the handle returned by a previous call to the DMBeginConfigureDisplays function (which is described on page 1-55); otherwise, supply this parameter with the value nil.
DESCRIPTION
The DMSetDisplayMode function sets a video device to the particular pixel depth you specify in the depthMode parameter and the display mode you specify in the mode parameter.
SPECIAL CONSIDERATIONS
The DMSetDisplayMode function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
kDMDriverNotDisplayMgrAwareErr –6228 The video driver for the display does not support the Display Manager
SEE ALSO
See the chapter “Slot Manager” in Inside Macintosh: Devices for information about functional sResource data structures. Your application can also use the SetDepth function, described in the chapter “Graphics Devices” in Inside Macintosh: Imaging With QuickDraw, to set the pixel depth of a video device.
DMMoveDisplay
The DMMoveDisplay function moves the boundary rectangle for a video device within the QuickDraw global coordinate plane.
pascal OSErr DMMoveDisplay (GDHandle moveDevice, short x, short y,
Handle displayState)
moveDevice A handle to the GDevice record for the video device whose boundary rectangle you wish to move.
x The horizontal coordinate on the QuickDraw global coordinate plane for the point to which you want to move the upper-left corner of the boundary rectangle for the video device represented by the GDevice record.
y The vertical coordinate on the QuickDraw global coordinate plane for the point to which you want to move the upper-left corner of the boundary rectangle.
displayState
To postpone Display Manager configuration checking, the rebuilding of desktop regions, and Apple event notification of Display Manager changes, supply this parameter with the handle returned by a previous call to the DMBeginConfigureDisplays function (which is described on page 1-55); otherwise, supply this parameter with the value nil.
DESCRIPTION
The DMMoveDisplay function moves the boundary rectangle for the video device whose GDevice record is specified in the moveDevice parameter to the point (x,y) in the QuickDraw global coordinate plane. If the video device controls the main screen, which always has the global coordinates (0,0), then all other video devices are offset by the horizontal distance –x and the vertical distance –y.
A boundary rectangle is the rectangle that links the local coordinate system of a graphics port to QuickDraw’s global coordinate system and defines the area of the pixel image or bit image into which QuickDraw can draw. The boundary rectangle is stored in either the pixel map or the bitmap contained in a GDevice record.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
SEE ALSO
See Inside Macintosh: Imaging With QuickDraw for more information about graphics ports, boundary rectangles, pixel maps, bitmaps, local coordinate systems, GDevice records, and QuickDraw’s global coordinate system.
DMDisableDisplay
The DMDisableDisplay function makes a video device inactive by removing its display area from the user’s desktop. Generally, your application should never need to use this function.
A handle to the GDevice record for the video device whose display you wish to disable; the video device specified here become inactive.
displayState
To postpone Display Manager configuration checking, the rebuilding of desktop regions, and Apple event notification of Display Manager changes, supply this parameter with the handle returned by a previous call to the DMBeginConfigureDisplays function (which is described on page 1-55); otherwise, supply this parameter with the value nil.
DESCRIPTION
By making a video device inactive, the DMDisableDisplay function disables the display controlled by the video device whose GDevice record you specify in the disableDevice parameter.
If you use DMDisableDisplay to disable the last remaining device in the device list, then DMDisableDisplay inserts into the device list a GDevice record that is not associated with any video device. If you specify the device for the main screen in the disableDevice parameter, then DMDisableDisplay picks another device and calls the DMSetMainDisplay function (described on page 1-51) to make its display the new main screen.
SPECIAL CONSIDERATIONS
If the DMDisableDisplay function calls the DMSetMainDisplay function to set a new main screen, the handle you pass in the disableDevice parameter does not point to the same GDevice record after DMDisableDisplay completes; instead, it points to the GDevice record for the new main screen. If you need to recover the GDevice record for the device you disabled, determine its display ID by using the GetDisplayIDByGDevice function, described on page 1-36 before calling DMDisableDisplay. Then use the GetGDeviceByDisplayID function, described on page 1-37, to obtain its GDevice record.
The DMDisableDisplay function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
DMEnableDisplay
The DMEnableDisplay function reactivates a display that was made inactive with the DMDisableDisplay function (described in the preceding section). Generally, applications should never need to use this function.
A handle to the GDevice record for the video device whose display you wish to make active.
displayState
To postpone Display Manager configuration checking, the rebuilding of desktop regions, and Apple event notification of Display Manager changes, supply this parameter with the handle returned by a previous call to the DMBeginConfigureDisplays function (which is described on page 1-55); otherwise, supply this parameter with the value nil.
DESCRIPTION
By making a video device active again, the DMEnableDisplay function adds to the user’s desktop the display area controlled by the video device whose GDevice record you specify in the disableDevice parameter.
If you enable a display when there are no active displays, DMEnableDisplay disables and removes from the device list the GDevice record created by DMDisableDisplay and calls the DMSetMainDisplay function (described on page 1-51) to make the device specified in the enableDevice parameter the main screen.
SPECIAL CONSIDERATIONS
If you enable a display when there are no active displays, DMEnableDisplay may call the DMSetMainDisplay function, which causes the enableDevice parameter to contain a handle to the GDevice record for the new main screen, not the video device whose handle you passed to DMEnableDisplay. If you need to recover the GDevice record for the device whose handle you pass in the enableDevice parameter, determine its display ID by using the GetDisplayIDByGDevice function, described on page 1-36 before calling DMEnableDisplay. Then use the GetGDeviceByDisplayID function, described on page 1-37, to obtain its GDevice record.
The DMEnableDisplay function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
DMSetMainDisplay
The DMSetMainDisplay function sets a display to be the main screen. Generally, your application should never need to call this function.
A handle to the GDevice record for the video device whose display you wish to make the main screen.
displayState
To postpone Display Manager configuration checking, the rebuilding of desktop regions, and Apple event notification of Display Manager changes, supply this parameter with the handle returned by a previous call to the DMBeginConfigureDisplays function (which is described on page 1-55); otherwise, supply this parameter with the value nil.
DESCRIPTION
The DMSetMainDisplay function sets the main screen to be the display controlled by the video device whose GDevice record you specify in the newMainDevice parameter; DMSetMainDisplay moves the menu bar to this display. QuickDraw maps the (0,0) origin point of the global coordinate system to the main screen’s upper-left corner, and other screens are positioned adjacent to it.
SPECIAL CONSIDERATIONS
After the DMSetMainDisplay function completes, the handle you passed in the newMainDevice parameter no longer points to the GDevice record for the display that you set as the main screen. Instead, it points to the GDevice record for the device controlling the display that had previously been the main screen. To obtain a handle to the main screen, you can use the Color QuickDraw function GetMainDevice.
The DMSetMainDisplay function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
kDMDisplayNotFoundErr –6229 There are no GDevice records for displays in the device list
SEE ALSO
The Color QuickDraw function GetMainDevice is described in the chapter “Graphics Devices” in Inside Macintosh: Imaging With QuickDraw.
See “When the User Moves the Menu Bar” beginning on page 1-11 for a discussion of how the Display Manager repositions windows after completing the DMSetMainDisplay function.
DMMirrorDevices
To turn video mirroring on, use the DMMirrorDevices function.
gD1 A handle to the GDevice record for the video device whose pixel image you want duplicated on another device.
gD2 A handle to the GDevice record for the video device where you want to duplicate the pixel image specified in the gD1 parameter.
displayState
To postpone Display Manager configuration checking, the rebuilding of desktop regions, and Apple event notification of Display Manager changes, supply this parameter with the handle returned by a previous call to the DMBeginConfigureDisplays function (which is described on page 1-55); otherwise, supply this parameter with the value nil.
DESCRIPTION
The pixel image contain in the GDevice record specified in the gD1 parameter is duplicated by the DMMirrorDevices function within the GDevice record specified in the gD1 parameter. This causes one display to mirror another.
SPECIAL CONSIDERATIONS
Your application should leave control of video mirroring to the user. However, if video mirroring is useful for your application (for example, if your application displays onscreen presentations), you might provide a control so that the user can switch to video mirroring directly from your application. In this case, the DMMirrorDevices function is useful to your application. Your control should also allow the user to turn video mirroring off; the DMUnmirrorDevice function, which is described next, supports this.
At the time of System Software version 7.5, mirroring works for only two video devices.
The DMMirrorDevices function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kDMMirroringOnAlready –6221 Video mirroring is already enabled
kDMWrongNumberOfDisplays –6222 System software version 7.5 supports video mirroring for only two displays
kDMMirroringBlocked –6223 Video mirroring currently blocked by a call to DMBlockMirroring
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
SEE ALSO
The chapter “Control Manager” in Inside Macintosh: Macintosh Toolbox Essentials describes how to implement controls in your application.
DMUnmirrorDevice
To turn off video mirroring, use the DMUnmirrorDevice function.
pascal OSErr DMUnmirrorDevice (GDHandle gDevice,
Handle displayState)
gDevice A handle to the GDevice record for the video device on which you no longer wish to mirror another’s pixel image.
displayState
To postpone Display Manager configuration checking, the rebuilding of desktop regions, and Apple event notification of Display Manager changes, supply this parameter with the handle returned by a previous call to the DMBeginConfigureDisplays function (which is described on page 1-55); otherwise, supply this parameter with the value nil.
DESCRIPTION
When the DMUnmirrorDevice completes, the display controlled by the video device specified in the gDevice parameter no longer contains the mirror image of another display.
SPECIAL CONSIDERATIONS
Your application should leave control of video mirroring to the user. However, if video mirroring is useful for your application (for example, if your application displays onscreen presentations), you might provide a control so that the user can switch to video mirroring directly from your application. In this case, the DMMirrorDevices function, described in the previous section is useful for switching video mirroring on, and DMUnmirrorDevice function is useful for switching it off again.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kDMGenErr –622 Indeterminate error
kDMMirroringNotOn –6225 Video mirroring is not currently enabled
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
SEE ALSO
The chapter “Control Manager” in Inside Macintosh: Macintosh Toolbox Essentials describes how to implement controls in your application.
DMBlockMirroring
To disable video mirroring, you can use the DMBlockMirroring function. Generally, your application should not use this function.
pascal OSErr DMBlockMirroring (void)
DESCRIPTION
The DMBlockMirroring function disables video mirroring until your application or another calls the DMUnblockMirroring function (described next), or until the user restarts the computer.
SPECIAL CONSIDERATIONS
The DMBlockMirroring function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kDMCantBlock –6224 Video mirroring already enabled and can’t be blocked; use DMUnMirrorDevice, then call DMBlockMirroring again
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
DMUnblockMirroring
To reenable video mirroring that was disabled with the DMBlockMirroring function (described in the preceding section), use the DMUnblockMirroring function. Generally, your application should not use this function.
pascal OSErr DMUnblockMirroring (void)
DESCRIPTION
The DMUnblockMirroring function reenables video mirroring that had been disabled with the DMBlockMirroring function.
SPECIAL CONSIDERATIONS
The DMUnblockMirroring function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
DMEndConfigureDisplays
If you used the DMBeginConfigureDisplays function (which is described on page 1-44), use the DMEndConfigureDisplays function when you are finished configuring the user’s displays.
The handle returned by a previous call to the DMBeginConfigureDisplays function (which is described on page 1-55).
DESCRIPTION
The DMEndConfigureDisplays function resumes Display Manager configuration checking, the rebuilding of desktop regions, and Apple event notification of Display Manager changes, all of which are postponed when you use the DMBeginConfigureDisplays function. Your application will then receive a single Display Notice event notifying your application of Display Manager changes, and your application can manager its windows accordingly.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
Adding and Removing Video Devices From the Device List
This section describes the Display Manager functions for manipulating the device list. Generally, your application should not use these functions but should instead allow system software to maintain the device list. These functions are described here for completeness only.
DMNewDisplay
The DMNewDisplay function calls the DMAddDisplay function (described on page 1-58) to add a video device to the device list and calls the DMEnableDisplay (described on page 1-49) to make it active. Generally, your application should not need to use this function.
pascal OSErr DMNewDisplay (GDHandle *newDevice,
short driverRefNum,
unsigned long mode,
unsigned long reserved,
DisplayIDType displayID,
ComponentInstance displayComponent,
Handle displayState)
newDevice A pointer to a handle to a GDevice record for the video device being added to the device list.
driver The reference number of the video device which you are adding to the device list. For most video devices, this information is set at system startup. The DMAddDisplay function passes the number supplied here to the InitGDevice function in that function’s gdRefNum parameter.
mode The depth mode. Used by the video device driver, this value sets the pixel depth and specifies color or black and white. The DMAddDisplay function passes the value supplied here to the InitGDevice function in its mode parameter.
reserved Pass the value nil in this parameter.
displayID A unique identification for the display. For new displays, supply this parameter with the value 0, which causes the Display Manager to generate a unique display ID for this device. If this display was removed, then pass the display ID in this parameter.
displayComponent
Reserved for future expansion. Pass the value nil in this parameter.
displayState
A display state. To postpone Display Manager configuration checking, the rebuilding of desktop regions, and Apple event notification of Display Manager changes, supply this parameter with the display state returned by a previous call to the DMBeginConfigureDisplays function (which is described on page 1-55); otherwise, supply this parameter with the value nil.
DESCRIPTION
The DMNewDisplay function adds a video to the device list and makes the device active. In the newDevice parameter, the DMNewDisplay function returns a pointer to the handle to the GDevice record for the newly added video device.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
DMAddDisplay
The DMAddDisplay function adds the GDevice record for a video device to the device list. Generally, your application should never call this function.
pascal OSErr DMAddDisplay (GDHandle addDevice, short driver,
unsigned long mode,
unsigned long reserved,
unsigned long displayID,
ComponentInstance displayComponent,
Handle displayState)
newDevice A handle to the GDevice record for the video device to add to the device list. This record is usually initialized by the DMNewDisplay function and its handle returned by DMNewDisplay in the newDevice parameter to DMNewDisplay.
driver The reference number of the graphics device which you are adding to the device list. For most video devices, this information is set at system startup. The DMAddDisplay function passes the number supplied here to the InitGDevice function in its gdRefNum parameter.
mode The depth mode. Used by the video device driver, this value sets the pixel depth and specifies color or black and white. The DMAddDisplay function passes the value supplied here to the InitGDevice function in its mode parameter.
reserved Pass the value NIL in this parameter.
displayID A unique identification for the display. For new displays, supply this parameter with the value 0, which causes the Display Manager to generate a unique display ID for this device. If this display was removed, then pass the display ID in this parameter.
displayComponent
Reserved for future expansion. Pass the value nil in this parameter.
displayState
A display state. To postpone Display Manager configuration checking, the rebuilding of desktop regions, and Apple event notification of Display Manager changes, supply this parameter with the display state returned by a previous call to the DMBeginConfigureDisplays function (which is described on page 1-55); otherwise, supply this parameter with the value nil.
DESCRIPTION
The DMAddDisplay function adds the GDevice record specified in the newDevice parameter to the device list. The DMAddDisplay function always adds the display represented by the GDevice record in the newDevice parameter as inactive. You must then call DMEnableDisplay, described on page 1-49, to make it active.
The DMNewDisplay (described on page 1-56) automatically calls DMAddDisplay and DMEnableDisplay. The only time DMAddDisplay needs to called directly is after the device has been removed by DMRemoveDisplay (described on page 1-59), but not yet disposed by DMDisposeDisplay (described on page 1-58).
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
kDMDisplayAlreadyInstalledErr –6230 The display is already in the device list and can’t be added
SEE ALSO
The InitGDevice function is described in the chapter “Graphics Devices” in Inside Macintosh: Imaging With QuickDraw.
DMRemoveDisplay
Although your application generally should never need to use this routine, the DMRemoveDisplay function makes memory available for adding video devices by removing a video device from the device list.
A handle to the GDevice record for a video device. The DMRemoveDisplay function does not actually dispose of this record, but instead removes it from the device list and places it into a list of devices maintained by the Display Manager. This internally maintained list allows the Display Manager to support such features as PowerBook docking by readding disposed video devices to the device list with the DMNewDisplay function (described on page 1-56).
displayState
To postpone Display Manager configuration checking, the rebuilding of desktop regions, and Apple event notification of Display Manager changes, supply this parameter with the handle returned by a previous call to the DMBeginConfigureDisplays function (which is described on page 1-55); otherwise, supply this parameter with the value nil.
DESCRIPTION
The DMDisposeDisplay function removes from the device list the device specified in the disposeDevice parameter.
SPECIAL CONSIDERATIONS
The DMRemoveDisplay function may call the DMSetMainDisplay function, which causes the disableDevice parameter to contain a handle to the GDevice record for the new main screen, not the video device whose handle was passed to DMDisposeDisplay. To recover the GDevice record for the disabled device, determine its display ID by using the GetDisplayIDByGDevice function, described on page 1-36 before calling DMRemoveDisplay. Then use the GetGDeviceByDisplayID function, described on page 1-37, to obtain its GDevice record.
The DMRemoveDisplay function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
DMDisposeDisplay
Although your application generally should never need to use this routine, the DMDisposeDisplay function disposes of the GDevice record for a video device.
A handle to the GDevice record for a video device.
displayState
To postpone Display Manager configuration checking, the rebuilding of desktop regions, and Apple event notification of Display Manager changes, supply this parameter with the handle returned by a previous call to the DMBeginConfigureDisplays function (which is described on page 1-55); otherwise, supply this parameter with the value nil.
DESCRIPTION
The DMDisposeDisplay function disposes of a GDevice record, releases the space allocated for it, and disposes of all the data structures allocated for it. The Display Manager calls this function when appropriate.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
Registering and Removing A Display Notice Event-Handling Procedure
This section describes the functions for registering and removing a procedure that responds to Display Manager changes.
DMRegisterNotifyProc
To obtain notification of Display Manager changes, you can handle the Display Notice event as a high-level event in your application’s event loop. Alternatively, you can register a procedure to which the Display Manager directly sends this Apple event; this is particularly useful if your application or utility does not receive Apple events or does not have an event loop.
pascal OSErr DMRegisterNotifyProc
(DMNotificationProcPtr notificationProc,
ProcessSerialNumberPtr whichPSN)
notificationProc
A pointer to your procedure that handles the Display Notice event.
whichPSN A pointer to the number of the process associated with your Display Notice event-handling procedure. If this process terminates, the Display Notice event-handling procedure is automatically removed. For example, the Monitors control panel supplies the Finder’s process number when registering its Display Notice event-handling procedure.
DESCRIPTION
The DMRegisterNotifyProc function registers a procedure that responds to the Display Notice event outside of an event loop.
Your Display Notice event-handling procedure should take one parameter: the Apple event describing the changes made to the display configuration, as shown here.
When the Display Manager sends your procedure the Display Notice event, your application or utility should respond by moving or resizing its windows and update any internally-maintained video device information as appropriate.
SPECIAL CONSIDERATIONS
The DMRegisterNotifyProc function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
SEE ALSO
For more information about the structure of the Display Notice event, see “Handling Events in Response to Display Manager Changes” on page 1-19. For information about handling the Display Notice event in your event loop, see “Handling the Display Notice Event as a High-Level Event” beginning on page 1-22. For information about responding to the Display Notice event, see “Managing Windows In Response to the Display Notice Event” on page 1-25.
DMRemoveNotifyProc
To remove your Display Notice event-handling procedure, use the DMRemoveNotifyProc function.
pascal OSErr DMRemoveNotifyProc
(DMNotificationProcPtr notificationProc,
ProcessSerialNumberPtr whichPSN)
notificationProc
A pointer to your Display Notice event-handling procedure.
whichPSN A pointer to the number of the process associated with your Display Notice event-handling procedure.
DESCRIPTION
The DMRemoveNotifyProc function removes the Display Notice event-handling procedure pointed to in the notificationProc parameter.
SPECIAL CONSIDERATIONS
The DMRemoveNotifyProc function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
Drawing the Desktop
The Window Manager and the Finder use the DMDrawDesktopRect and DMDrawDesktopRegion functions to draw portions of the desktop. Your application should never need to call these functions.
DMDrawDesktopRect
The Window Manager and the Finder use the DMDrawDesktopRect function to draw a portion of the desktop. Your application should never need to call this function.
pascal void DMDrawDesktopRect (Rect* globalRect)
globalRect The rectangle, specified in global coordinates, to be drawn.
DESCRIPTION
The DMDrawDesktopRect function draws the desktop rectangle specified in the globalRgn parameter.
SPECIAL CONSIDERATIONS
The DMDrawDesktopRect function may move or purge memory blocks in the application heap and should not be called at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
DMDrawDesktopRegion
The Window Manager and the Finder use the DMDrawDesktopRegion function to draw a region of the desktop. Your application should never need to call this function.
globalRgn A handle to the region, specified in global coordinates, to be drawn.
DESCRIPTION
The DMDrawDesktopRegion function draws the desktop region specified in the globalRgn parameter.
SPECIAL CONSIDERATIONS
The DMDrawDesktopRegion function may move or purge memory blocks in the application heap and should not be called at interrupt time.
RESULT CODESnoErr 0 No error
paramErr –50 Invalid value passed in a parameter
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
Application-Defined Function
This section describes the Display Notice event-handling procedure you can define to respond to the Display Notice event outside of an event loop.
DMNotificationProc
To obtain notification of Display Manager changes, you can handle the Display Notice event as a high-level event in your application’s event loop. Alternatively, you can use the DMRegisterNotifyProc function, described on page 1-61, to register an application-defined procedure to which the Display Manager directly sends this Apple event; this is particularly useful if your application or utility does not receive Apple events or needs to respond to the Display Notice event outside of an event loop.
In the notificationProc parameter to DMRegisterNotifyProc, you supply a pointer to your Display Notice event-handling procedure. Your procedure should take one parameter: the Apple event describing the changes made to the display configuration, as shown here.
When the Display Manager sends your procedure the Display Notice event, your application or utility should respond by moving or resizing its windows and update any internally-maintained video device information as appropriate.
To remove your callback procedure, use the DMRemoveNotifyProc function, which is described on page 1-62.
SEE ALSO
For more information about the structure of the Display Notice event, see “Handling Events in Response to Display Manager Changes” on page 1-19. For information about handling the Display Notice event in your event loop, see “Handling the Display Notice Event as a High-Level Event” beginning on page 1-22. For information about responding to the Display Notice event, see “Managing Windows In Response to the Display Notice Event” on page 1-25.
kDMMirroringOnAlready –6221 Video mirroring is already enabled
kDMWrongNumberOfDisplays –6222 System software version 7.5 supports video mirroring for only two displays
kDMMirroringBlocked –6223 Video mirroring currently blocked by a call to DMBlockMirroring
kDMCantBlock –6224 Video mirroring already enabled and can’t be blocked; use DMUnMirrorDevice, then call DMBlockMirroring again
kDMMirroringNotOn –6225 Video mirroring is not currently enabled
kSysSWTooOld –6226 Some piece of system software (such as the Process Manager) is too old for the Display Manager to operate
kDMSWNotInitializedErr –6227 Used internally by the Display Manager, this error occurs when required pieces of system software are not initialized
kDMDriverNotDisplayMgrAwareErr –6228 The video driver for the display does not support the Display Manager
kDMDisplayNotFoundErr –6229 There are no GDevice records for displays in the device list
kDMDisplayAlreadyInstalledErr –6230 The display is already in the device list and can’t be added
Display Manager Glossary
active deviceA video device whose display area is included in the user’s desktop.
default display modeA required display mode that appears the first time a user turns on a display.
depth modeA constant (or its value from an enumerated list) that represents a pixel depth supported by a video device. Also called video mode.
displayAn output device—such as a video monitor or flat-panel display—on which an application can show interactive visual information—such as text for a document or data for a spreadsheet. Also called monitor.
display IDA long integer used by the Display Manager to uniquely identify a display.
Display ManagerA set of system software routines that allow users to dynamically change the arrangement and display modes of the displays attached to their computers. Users can move displays, add or remove displays, switch multiple-scan displays to show more or less of the desktop, and move the menu bar from one display to another—without restarting their computers.
display modeA combination of several interrelated capabilities for a display that can be altered by the Display Manager without restarting the computer. These capabilities include the refresh rate, number of onscreen pixels, and scan timings.
inactive deviceA video device whose display area does not appear in the user’s desktop.
main screenIn a drawing environment with multiple screens, the screen with the menu bar. QuickDraw maps the (0,0) origin point of the global coordinate system to the main screen’s upper-left corner, and other screens are positioned adjacent to it. Compare startup screen.
mirroring See device mirroring.
monitor See display.
multiple-scan displayA display capable of operating at multiple horizontal and vertical scan timings.
optional display modeA display mode that is not required by the Display Manager for a particular type of display (such as a 19-inch video monitor) but that can be supported by the display anyway. A list of optional display modes appears when the user holds the Option key and clicks the Options button in the Monitors control panel. Compare required display mode.
required display modeA display mode that a particular type of display (such as a 19-inch video monitor) is required by the Display Manager to support. Compare optional display mode.
video deviceA piece of hardware, such as a plug-in video card or a built-in video interface, that controls a display.
video mirroring The duplication of the windows, menu bar, and desktop from the main screen onto another display. Video mirroring is helpful to a user who, for example, has prepared a presentation on a PowerBook computer and wants to show the presentation to an audience viewing a larger display that is also attached to the PowerBook.